create-skill herzien: skills-ontologie als skill, spec-conforme frontmatter en een validator - #68
Merged
Merged
Conversation
Rewrites create-skill around the CEDA skills ontology and the Agent Skills specification, and moves the ontology itself from a document into a skill. create-skill v2: - external-first search as a blocking first step (skills.sh registry plus a fixed list of plugin sources; explicitly not the locally installed set, which differs per machine) - blocking provenance gate: content must come from a real session, runbook, review or expert, recorded in ceda-source (self / path / url / intern:) - classification via AskUserQuestion menus instead of open questions - description rules with both exclusion-clause forms, plus an overlap check that also updates the *existing* skill's description in the same PR - validation loop before the draft is presented Spec compliance: - frontmatter carries only the six spec fields; all CEDA fields move under metadata: as ceda-* strings - allowed-tools is a space-separated string, not a YAML list - the bundles: field is dropped entirely — it is not in the spec and would not work anyway, since the agent reads the body; load conditions now live in a "Gebundelde bestanden" body section New: scripts/validate-skill.py (stdlib only) checks both rule sets, including name/description constraints, enum values, binding-without-hook, missing source, and bundled files that are never referenced from the body. It finds 10 pre-existing spec violations in the collection (see #59). New: skills-ontology reference skill is now the source of truth for the model (ceda-source: self), with the argumentation bundled in references/rationale.md. docs/skills-ontology-CEDA-uitwerking.md is removed; the remaining programme moved to #49. Templates are a minimal skeleton plus a menu of form patterns with an admission question each, rather than a fill-in-the-blanks form — the sections that make a skill good (symptom table, decision tree, named gotcha headings) are conditional by nature.
docs/skill-gaps.md was a dated snapshot ("peildatum 21 juli 2026") of work
that nobody maintains. Its six gaps are now issues, with the reasoning per
gap carried over rather than summarised:
- #61 skill-lifecycle (was Gap 6): review-skill, dedup-skills, audit-skill
- #63 interpretation and action after the analysis (Gap 1)
- #64 data governance, AVG and reference architecture (Gap 2)
- #65 intake with institutions (Gap 3)
- #66 test conventions and reproducibility (Gap 4)
- #67 onboarding team members (Gap 5)
The category discussion and the proposed ordering moved to a comment on #60.
CorneeldH
changed the title
This was referenced Aug 14, 2026
Contributor
Author
|
Deze skill triggert automatische test: er wordt eerst door sub-agent gekeken wat het default gedrag is. Dat duurt wel lang.. Misschien niet erg voor aanmaken skills? Misschien wel? |
De validator kende alleen het spec-plafond van 1024 tekens, en description-schrijven.md las "budget: 1024" als streefwaarde. Daardoor kreeg een skill die je expliciet aanroept hetzelfde triggeroppervlak als een skill die moet vuren op een geplakte foutmelding — inclusief paden en schema-details die elke sessie in context staan. - description-schrijven.md: tabel die het oppervlak aan ceda-activation koppelt (command/chained <=400 tekens, ambient het volle budget), plus een sectie over wat er niet in hoort met de toets "verandert dit zonder dat de trigger verandert, dan hoort het in de body" - het "bij twijfel opdringeriger"-advies beperkt tot ambient - validate-skill.py: waarschuwing bij command/chained boven 400 tekens, en bij mechaniek (directorypaden, placeholders, bestandsextensies, vlaggen) in de description - create-skill's eigen description ingekort van 665 naar 376 tekens De mechaniek-check matcht bewust niet op losse schuine strepen: type/origin/scope en connector/command zijn opsommingen, geen paden.
Sluit de skill-levensloop: aanmaken was gedekt door create-skill, beoordelen, ontdubbelen en auditen niet. Alle drie zijn gebouwd met create-skill en getest volgens RED-GREEN: eerst een baseline-run per taak zonder de skill, daarna dezelfde taak met de skill. De baselines vonden ruim voldoende maar sloegen door naar een actie zonder het pad te controleren -- publiceren zonder te vragen, rm -rf zonder na te denken over kopieen in andere repo's, een chain lezen als kapotte links in plaats van als opgetelde rechten. Dat is wat deze drie begrenzen. review-skill (workflow, own) - blokkerende scope-gate: een PR met twee skills of met inhoud die al op main staat is niet reviewbaar; stoppen en terugvragen - validator-output geldt als bevestigd defect, geen alinea per punt - vier oordeelsvragen: scope, overlap, herkomst, type-classificatie - posten heeft een eigen akkoord, los van "review deze PR" - geen Write/Edit: de skill onder review is data, geen instructie dedup-skills (workflow, own) + references/deprecatiepad.md - detectie komt uit de validator, de skill draagt het oordeel en het pad - drie uitkomsten: samenvoegen, parametriseren, houden-met-exclusion-clause - ablation verplicht voor "overbodig", behalve bij een aantoonbare kloon - deprecatiepad voor een collectie die via npx skills add gekopieerd wordt: vervanger eerst, tombstone, kopieen in de org opzoeken, dan pas weghalen - geen ceda-deprecated-veld; de description draagt de doorverwijzing externe-skill-audit (reference/knowledge, own) - vier oppervlakken: tools, netwerk, gebundelde scripts, chains - een chain telt rechten op die in geen enkele allowed-tools zichtbaar zijn; het deel dat onvertrouwde inhoud verwerkt krijgt geen schrijfrechten - de audit eindigt in een ingevulde allowed-tools, niet in "ziet er schoon uit" validate-skill.py - nieuwe fout: twee directories die dezelfde name claimen - exclusion-clause-check herschreven. De oude substring-match herkende "buitenwereld" als begrenzing en "gebruik dan deze skill" als doorverwijzing, en verzweeg daardoor het enige paar in de collectie met een byte-identieke description (ui-designer / ontwerper-digitaal-product). De verwijzende vorm moet nu de andere skill noemen, de begrenzende vorm een scope. create-skill - verificatie-eis gerepareerd: het totale aantal overlap-waarschuwingen is geen maat, want de corpusdrempel verspringt als de collectie groeit - vorm-patronen aangevuld met twee stukken uit superpowers:writing-skills: vorm-bij-faaltype, en de micro-test met no-guidance control - dode verwijzingen naar het verwijderde docs/skill-gaps.md weg Refs #61
Generieke versie van de skill uit ceda-workshop-starter, losgemaakt van de
workshop-harness. Die versie leest voortgang.md, .claude/.sessie-status.md en een
rol uit een statusbestand, en schrijft reflectie.md in de projectrepo — alle drie
bestaan alleen daar.
Wat deze versie doet:
- context uit twee git log-commando's, verder niets: naam, commit-range en de
Entire-Checkpoint-trailers als die er zijn
- output is een markdownbestand in cedanl/repo-context-as-data onder
data/<datum>/<repo>/, append-only (nieuw bestand, nooit overschrijven)
- frontmatter draagt de commit-range, zodat de menslaag (waarom, wat bleef
liggen) later te koppelen is aan de machinelaag die checkpoint-tooling per
commit vastlegt
- verbruik wordt geteld uit het sessietranscript in plaats van de gebruiker /cost
te laten draaien; scripts/sessie-tokens.py print het als YAML
- elke vraag is optioneel en een dun antwoord is een antwoord: geen doorvragen,
geen verplichting iets goeds te melden
- eigen waarnemingen van de agent staan apart onder "Wat de agent zag", alleen
aanwijsbaar (een skill die niet vuurde, een correctie, een omweg), en de
deelnemer mag ze schrappen voor het wegschrijven
Getest met een ablation: zonder de skill gaat het model coachen en oordelen
("bewust != blind, dus geen echte blinde vlek"), parafraseert het de antwoorden
en levert het geen artefact. Met de skill blijven de woorden van de deelnemer
staan en komt er een concept met volledige SHA-range.
generate-slides-retro-simple krijgt een exclusion-clause die terugwijst, omdat de
descriptions overlappen op board/commits/review/sprint.
Reflectie gaat over eigen handelen; deze skill legt de sessie vast, inclusief wat de agent deed en wat er niet vuurde terwijl het had gepast. Evaluatie was het alternatief maar brengt een oordeelsframe mee dat vecht met de kernregel van de skill (niet oordelen, woorden van de deelnemer overnemen), en binnen CEDA betekent evaluatie al iets anders: instrumenten zoals evaluatietool-selectie. Meeverhuisd: directorynaam, name, ceda-id, het pad in de data-repo (sessie-terugblik-<naam>.md), type in de frontmatter van het artefact, de commit-message van de PUT, en de exclusion-clause in generate-slides-retro-simple. "Reflectie" blijft als triggerwoord in de description staan — mensen typen dat, en de skill hoort er gewoon op te vuren. ceda-source blijft naar het sessie-reflectie-bestand in ceda-workshop-starter wijzen; dat heet daar nog zo.
Merged
13 tasks
feat(skills): review-skill, dedup-skills, externe-skill-audit en sessie-terugblik
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request Description
Type of Change
Description of Changes
create-skillherschreven rond de skills-ontologie én de Agent Skills-specificatie, en het model verhuisd van een document naar een skill.create-skill(.claude/skills/create-skill/) — vervangen op z'n plek,ceda-version: "2.0.0"npx skills find) en Claude Code-plugins. Bewust een vaste lijst bronnen en nietclaude plugin marketplace list— dat leest de machine van wie het toevallig draait, en de uitkomst van deze stap moet voor iedereen gelijk zijn.ceda-source:self, een pad, een publieke url, ofintern:<vindplaats>voor iets achter een inlog — met de eis dat de skill dan zelfstandig leesbaar is, want wie hem laadt kan de bron mogelijk niet openen.Spec-conformiteit — dit raakte het hele schema
metadata:alsceda-*-strings;allowed-toolsis een spatie-gescheiden string, geen YAML-lijst.bundles:-veld is geschrapt. Het staat niet in de spec en zou sowieso niet werken: de agent leest de body, niet onze metadata. Laadcondities staan nu in een## Gebundelde bestanden-sectie — zoals de SDP-skills al deden.ceda-sourcegeldt nu voor élke skill, ook workflows.Nieuw:
scripts/validate-skill.py(stdlib-only, draait ook in een repo die de skills vianpx skills addbinnenhaalde). Controleert spec én ontologie: naamregels, descriptionlengte, enum-waarden,binding: hardzonder hook, ontbrekendesource, en gebundelde bestanden die nergens in de body genoemd worden. Overlap-detectie filtert eerst woorden weg die in >12% van alle descriptions voorkomen, zodat "maak" en "levert" geen ruis geven.Nieuw:
skills-ontology— reference-skill die nu de bron van het model is (ceda-source: self), met de argumentatie inreferences/rationale.md.Templates: een minimaal skelet plus een menu van vormpatronen met per patroon een toelatingsvraag, in plaats van een invulformulier. De secties die een skill goed maken — symptoom-tabel, beslisboom, koppen die het feit noemen — zijn conditioneel van aard; een ceremoniële lege sectie kost context en levert niets. Het diagnose-patroon (kennis die een procedure is, zoals
surf-sdp-helm-flux) is expliciet erkend als vorm binnenreference.Documenten opgeheven:
docs/skills-ontology-CEDA-uitwerking.mdendocs/skill-gaps.md. Twee bronnen voor hetzelfde model is precies de drift die de ontologie elders bestrijdt, en een gap-analyse met peildatum is werk dat in issues hoort.Related Issues
Closes #49
Voortgekomen uit deze PR: #59 (tien spec-fouten in de collectie), #60 (migratie), #61 (lifecycle-skills), #62 (evals), #63 t/m #67 (de vijf resterende skill-gaps).
Comparison: Before and After
Before:
create-skillwas een interview van vijf vragen met vier skill-types (Actie/Review/Generatie/Wizard, plus Kennis uit #47). Frontmatter:nameendescription. Geen zoektocht naar bestaande skills, geen herkomstvraag, geen validatie. Het ontologie-model stond in een document van 450 regels naast de skills; de gap-analyse in een tweede document met een peildatum.After:
Tien stappen met twee blokkerende poorten (extern eerst, herkomst). Classificatie volgens de ontologie, spec-conforme frontmatter, en een validator die faalt op elf regels. Het model staat in
skills-ontologyen is daarmee zelf een skill die laadt wanneer je hem nodig hebt; het openstaande werk staat op het board.Testing Instructions
Geautomatiseerd:
De validator is ook negatief getest met een opzettelijk kapotte skill (ontbrekende
source,binding: hardzonder hook, bundle zonder laadconditie,name≠ directory): alle regels vuurden.Handmatig, nog niet gedaan: de herziene
create-skillis nog niet op een echte taak gedraaid. De bronnen zijn expliciet dat één ronde uitvoeren-en-herzien de goedkoopste kwaliteitsslag is. Dat gebeurt bij het bouwen van de lifecycle-skills (#61); correcties die daar nodig blijken horen terug in deze skill.Validation
styler::style_active_file()has been run — n.v.t., geen R in deze PRDependencies
Geen nieuwe. De validator gebruikt uitsluitend de Python-standaardbibliotheek, zodat hij ook draait in een repo die de skills via
npx skills add cedanl/.githubheeft binnengehaald. Optioneel:skills-ref validate(de referentie-implementatie van de spec) enclaude plugin eval --ablationvoor de baseline-meting in #62.Additional Information
Twee dingen die om een besluit vragen bij review:
anthropics/skills,obra/superpowers,vercel-labs/agent-skills, de official marketplace) zijn mijn inschatting, geen teambesluit. Aanvullen of schrappen kan in deze PR.namedie afwijkt van hun directory engenerate_slides_retroheeft een underscore, wat volgens de spec ongeldig is. Repareren betekent aanroepnamen wijzigen; dat is een eigen afweging per skill.Checklist
Nagekomen: description-lengte gekoppeld aan
ceda-activationAanleiding: bij het bouwen van een nieuwe skill met deze workflow kwam er een description van 942 tekens uit, vol mechaniek (doelrepo, pad, schema, het
git log-commando). De validator gaf groen — hij kende alleen het spec-plafond van 1024 — endescription-schrijven.mdlas "budget: 1024" als streefwaarde, met daarbovenop het advies "bij twijfel iets te opdringerig".Dat advies klopt voor een
ambientskill, die moet vuren op een geplakte foutmelding die niemand aankondigt. Voor een skill die je aanroept met/naamwerkt het averechts: de activatie is al geregeld en elk extra woord concurreert alleen nog met de descriptions van alle andere skills, elke sessie opnieuw.ceda-activationkoppelt (command/chained≤400 tekens,ambienthet volle budget)references/description-schrijven.mdambientcommand/chainedboven 400 tekensscripts/validate-skill.py<placeholders>, bestandsextensies,--vlaggenSKILL.mdDe mechaniek-check matcht bewust niet op losse schuine strepen. Eerste versie deed dat wel en sloeg aan op
type/origin/scopeenconnector/command— opsommingen die in een goede description thuishoren. Nu alleen echte signalen: bekende directorynamen, placeholders, extensies, vlaggen.